Commentator™ allows you to copy all of your Finder Get Info comments into a text file. After rebuilding the desktop or restoring your disk from a backup, you can replace lost comments from the text file. Commentator requires System 7 or later, but is capable of extracting comments from an old-style Desktop resource file as used prior to System 7. (The ability to restore comments to a resource file is not supported.)
Shareware Registration:
Commentator is a copyrighted software product distributed as shareware. You are free to use it for a reasonable evaluation period and to pass on to others unmodified copies of the archive file containing Commentator and its accompanying Register application. If you decide to keep it, you are expected to pay a shareware license fee of $10 (U.S.) for use by one individual or on one computer. A site license fee of $150 permits use of the software throughout a school, company or other organization at one geographic location. A world-wide site license fee of $500 permits use of the software throughout a school, company or other organization at all of its locations. (If you will be using Commentator to back up comments from multiple networked machines, you should purchase a site license or multiple individual licenses.) Upon request, site licensees will be provided with a copy of the application customized with the name of their organization, and with the shareware reminder turned off.
Payments are processed by Kagi Shareware, a service company located at 1442A Walnut Street #392-KD, Berkeley, California 94709-1405, USA. Registration is best accomplished by running the accompanying Register application, which describes how to pay by cash, check, credit card or First Virtual. Simply enter your registration information, including the number of individual licenses you require (or select Site or World-Wide). Then Save, Copy or Print the data from Register and send it along with your payment to Kagi Shareware.
If you are paying by credit card or First Virtual your registration information may be sent to Kagi Shareware via email (shareware@kagi.com) or fax (+1 510 652 6589). You can either Copy the data from Register and paste it into the body of an email message, or Save the data to a file and attach that file to an email message. If you have a fax modem, you can just Print the data to Kagi’s fax number.
If paying by cash or check you should print your information from the Register application and send it to Kagi’s postal address along with your payment. Checks in currencies other than U.S. dollars or drawn on non-U.S. banks cannot be processed due to the prohibitive bank fees involved. However, cash in several different currencies is accepted.
Kagi Shareware cannot invoice your company for payment, but the Register application can be used to generate an invoice which you may then submit in triplicate to your Accounts Payable department on Kagi’s behalf. You might want to highlight the line that asks them to include a copy of the form with their payment.
In the event that the Register application is missing, you may simply send the appropriate fee by check (payable to Kagi Shareware in U.S. dollars, drawn on a U.S. bank) to Kagi Shareware at the address shown above. Write on your check the name and version number of the application you are registering. We will also need the name of the person or organization to whom the software should be registered and an email address or other means of communication. If you are purchasing a site license and want a customized version of the application as described above, please include a note to that effect with your registration and supply the postal address to which we should send the software.
Payments submitted by email are processed within 3 or 4 days, while those submitted by fax may take up to 10 days. Payments via post may take up to 10 days in addition to postal delays. In any case, if you supply a correct Internet email address you will receive an email acknowledgement when your payment has been processed. Please do not email or fax payment forms that indicate Cash, Check or Invoice as the method of payment, because without the payment the forms cannot be processed.
Extracting Comments:
This description assumes that you have not changed any of the program’s Preferences from their ‘factory standard’ values.
To extract the Get Info comments from a particular volume, first select Open… from the File menu. A directory dialog box will appear, asking you to select a volume or a text file. Navigate to the volume whose comments you want to save; there you should see a file named Desktop DB. Double-click on the Desktop DB file, or select it and click the Open or Select button. (You may also select the volume itself and click the Select button. Use this technique if you do not see a Desktop DB or Desktop file on the volume.) Commentator will extract your comments into a file named Comment Text in the same location.
During this operation a progress window will be shown. Upon completion, the window will disappear automatically.
Restoring Comments:
This description assumes that you have not changed any of the program’s Preferences from their ‘factory standard’ values.
To restore your Get Info comments, first select Open… from the File menu. A directory dialog box will appear, asking you to select a volume or a text file. Navigate to the volume whose comments you want to restore; there you should see a file named Comment Text that contains your saved comments. Double-click on the Comment Text file, or select it and click the Open or Select button.
A second directory dialog box will then appear, asking you to select a volume or Desktop file to receive the restored comments. You should see a file named Desktop DB in the current folder. Double-click on the Desktop DB file, or select it and click the Open or Select button. (You may also select the volume itself and click the Select button. Use this technique if you do not see a Desktop DB file on the volume.) Commentator will read your comments from the text file and restore them to the desktop database.
During this operation a progress window will be shown. Upon completion, the Stop button in the progress window will change to say Done. Click it to dismiss the window.
Perusing Comment Text Files:
You may examine a Comment Text file using any text editor or word processor. The contents are best viewed in a small font, with word-wrap off. A text editor such as EDIT II or BBEdit tends to be better for this purpose than a word processing application.
The file format is intended to be self-explanatory. You may remove entries, change filenames or edit comments if you wish, provided that you do not violate the constraints of the file format. Note that ASCII control characters embedded in comments or filenames are represented as two-character escape sequences such as ‘^M’ for carriage return.
Preferences:
The factory standard preferences are set to ‘safe’ values, but you may have occasion to change them. To do so, first select Preferences… from the Edit menu. A window will appear showing the various preference options, which are described below.
See Desktop resource files - if this box is checked, you will be able to see old-style Desktop resource files (which normally are invisible) in Commentator’s directory dialogs; otherwise, the existence of these files is ignored. You should check this box if you want to extract comments from a System 6 volume or a floppy disk. If you converted from System 6 to System 7 at some time in the past, or if you switch back and forth between the two, you will probably have a Desktop resource file lying around on each converted volume. It is possible to extract comments from such a file and restore them to a System 7 desktop database.
Turn off registration reminder - once you have paid for and registered your copy of Commentator, check this box to turn off the notation ‘(Unregistered)’ that appears in the title bar of Commentator progress windows. See above for instructions on how to register.
List all files and folders, even those without comments - if this box is checked, Commentator’s output text file will list every file and folder that was examined on the selected volume. Normally, only those that have comments are listed.
Auto-extract from Desktop DB to “Comment Text” - if this box is checked, Commentator will not ask you for an output filename when extracting comments from a System 7 desktop database. Instead, it will automatically use the name shown, overwriting the file if it already exists. If you wish to save comments to a different file or in a different place, simply uncheck this box and you will be given the opportunity to specify a name at the appropriate time.
Auto-extract from Desktop resource file to “Comment Text (S6)” - if this box is checked, Commentator will not ask you for an output filename when extracting comments from an old-style Desktop resource file. Instead, it will automatically use the name shown, overwriting the file if it already exists. If you wish to save comments to a different file or in a different place, simply uncheck this box and you will be given the opportunity to specify a name at the appropriate time.
Save alias records - if this box is checked, each entry in the output text file will include an encoded alias record. This will allow highly reliable matching of files and folders during comment restoration, but the output file will be considerably larger. If speed and disk space are not of major concern, you may wish to leave this box checked so that the ‘Attempt match by alias’ option can be employed when the time comes to restore your comments.
Attempt match by alias - this and the following three options determine how Commentator attempts to find files and folders when restoring comments. The most sophisticated and reliable technique involves the use of alias records, which will allow a file or folder to be matched even if it has been moved, renamed or restored from backup. However, this technique is useful only if you are restoring comments to the same volume from which they were extracted originally.
Attempt match by parID & name - matching by parent directory ID and file/folder name is fast and generally works well, provided that you are restoring comments to the same volume from which they were extracted originally. Unlike matching by alias or pathname it won’t succeed on a volume that has been copied from a backup device, and in such circumstances it should not be selected. This is the best technique to use if all you want to do is save your comments, perform a desktop rebuild and then restore them.
Attempt match by pathname - this will work after a desktop rebuild and also after copying a volume from a backup device. It is therefore in some sense the ‘safest’ option. However, it is slower than matching by parent directory ID and item name, and unlike that technique it may fail miserably if you have moved or renamed folders since the comments were extracted.
Attempt match by ‘hard’ ID - every folder has a so-called ‘hard’ directory ID that uniquely identifies it within the volume and that survives moving, renaming and desktop rebuilds. A file may also have such an ID (for example, if an alias to the file has been created at some time in the past, perhaps by Commentator itself) but need not. Therefore this option will generally not suffice to restore all of your comments, but you may wish to use it in conjunction with either of the above two options when you are attempting to restore comments to a volume that has been modified.
Notify on failure to match - when it looks for a file or folder, Commentator applies each of the selected ‘Attempt match by…’ options in top-to-bottom order. If none of these succeeds, you may wish to know about it, since it means that one of your comments will not be restored. If this box is checked, Commentator will notify you whenever this occurs and give you the option to ignore the error or stop.
Replace existing comment - before restoring a comment, Commentator checks to see if the file or folder already has one. If so, the existing comment will not be replaced unless you have checked this box. Note than a replacement that is empty or is identical to the existing comment will always be skipped, regardless of the setting of this option. Such entries will not be listed as ‘rejects’ (see below).
Notify before replacing - if this box is checked, Commentator will notify you before replacing an existing comment. You will be given the option to skip the entry, in which case it will be treated as a ‘reject’.
Notify before truncating - comments stored in a System 6 Desktop resource file may be up to 255 characters in length. However, System 7 restricts comments to a maximum of 199 characters for most volumes. If you extract comments from a System 6 Desktop resource file and attempt to restore them to a System 7 desktop database, overly-long comments will be truncated. If you check the ‘Notify before truncating’ box, Commentator will notify you whenever this occurs and give you the option to skip the entry, in which case it will be treated as a ‘reject’.
Record “Comment Rejects” - if this box is checked, rejected entries will be recorded in a text file named Comment Rejects. This includes entries for which no match was found, those for which comment restoration failed due to an error (such as a disk I/O error), and those that you chose to skip (in response to notification as described above). It does not include entries that were skipped because the replacement comment was empty or identical to the existing one; and if you chose not to replace existing comments, it does not include entries that were skipped because the file or folder already had a comment. The format of a Comment Rejects file is the same as that of a Comment Text file, and it may be used as input to a subsequent comment restoration attempt.
Saving Preferences:
When you have the preferences the way you want them, you may click the OK button to accept your changes and apply them temporarily. They will be discarded when you quit the program. If you want to make your changes permanent, click Save instead; your preference values will be saved in a file named Commentator Prefs that will be created in the Preferences folder within your System Folder.
The Cancel button undoes any changes you have made since selecting the Preferences… menu item. Defaults sets all the options to their factory standard values.
Drag and Drop Operation:
You may drag one or more volumes from the desktop onto Commentator’s icon. This will automatically select the Desktop DB and/or Desktop resource file from each volume for processing. If the ‘Auto-extract’ options are checked, operation will be fully automatic in the absence of errors.
You may also drag and drop a folder (in which case only that folder and its contents will be processed) or a text file (to restore comments). Comment restoration always requires manual intervention, however, to select the target volume.
If you install Commentator and discover that it will not allow you to drag and drop anything, the most likely cause is a problem with your desktop database. Rebuilding the desktop should correct this — but do remember to save your comments first!
Remote or Non-Apple Volumes:
Commentator should work for any Macintosh-compatible volume that supports the interface provided by System 7 to extract or restore comments. For remote volumes, be sure that you have whatever file-sharing permissions may be necessary to perform these operations. If no Desktop DB or Desktop file is visible, you may select the volume by using drag-and-drop or by means of the Select button in Commentator’s directory dialog box.
No Warranty:
The author has striven to make Commentator bug free, but cannot guarantee its correct operation in all circumstances. If you are unsatisfied with its performance you may request a refund; however, in no event will the author or any other party involved in the production, sale or distribution of the software be liable for any loss or damage caused or in any way contributed to by its use.
Commentator is supplied as is. Omicron Software Systems disclaims any warranty relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Neither Omicron nor its agents will be liable for any direct, indirect, special, incidental, consequential or other damages resulting from use of the software or any defect in the software, even if advised of the possibility of such damages.
Release History:
01/17/96, Version 1.0 — First public release.
Credits:
Commentator was designed and written by Kelvin Delbarre. The author’s company, Omicron Software Systems, is a contract software development firm specializing in UNIX kernel and system software development. Comments and questions should be directed to the author (kd@kagi.com) via email, while registration requests and payments should be sent to Kagi Shareware (shareware@kagi.com) as noted above.
